Using the Jobs API

AJL's Jobs API (Application Programming Interface) processes raw job posting data so that job postings do not have to be created manually using the AJL job posting builder. You can also use the Jobs API to edit or delete job postings. Typically, third-party recruiters or large employers with a great number of job postings use the Jobs API. You must develop, purchase, or use an open-source RESTful client to use the API. Using the Jobs API requires basic knowledge of software development and web services.

You (or the employer whose job postings you manage) must also have an approved employer account in each AJL website in which you want to post jobs. Once your employer account has been approved, you must generate a Jobs API token to use the API or to authorize a third-party to use the API on your behalf. If you are managing your company's job postings, you will use your unique token with your username to submit requests to the Jobs API. If you are a third party managing jobs for multiple employers, you will need the username and API token for each employer you serve.

If you have used the Jobs API in the past, we recommend updating to Version 2. This includes updated Headers and Body text, as described below. However, Version 1 is still supported.

Creating/Viewing an API Token

Do not create an API token unless you are ready to use the Jobs API yourself or if you plan to allow a third party to post your jobs.

  1. Navigate to My Company Profile and click the Job API accordion. The Job API section expands.

  2. Click Display Token. A confirmation message displays at the top of the page.

  3. Click the Job API accordion. The Job API section expands.

  4. Click Display Token. The token displays

How the Jobs API Works

To use the Jobs API, you need a RESTful client, which is a program that lets you build HTTP requests. To make a request, you need to include the URL, Header, Method, and Body. The body will vary depending on the method.

URL

An endpoint is a unique URL that makes up part of an API. For the Jobs API, each state using AJL has a unique endpoint. If you wish to post jobs across multiple states using AJL, you must use separate endpoints for each state:

  • Alabama: https://joblink.alabama.gov/api/jobs
  • Arizona: https://www.azjobconnection.gov/api/jobs
  • Arkansas: https://www.arjoblink.arkansas.gov/api/jobs
  • Delaware: https://joblink.delaware.gov/api/jobs
  • Idaho: https://idahoworks.gov/api/jobs
  • Illinois: https://illinoisjoblink.illinois.gov/api/jobs
  • Kansas: https://www.kansasworks.com/api/jobs
  • Maine: https://joblink.maine.gov/api/jobs
  • Oklahoma: https://okjobmatch.com/api/jobs
  • Vermont: https://www.vermontjoblink.com/api/jobs

Method

The request methods for the Jobs API are POST (create job posting[s], PATCH (update an existing job posting), and DELETE (delete the job posting).

If you need to patch or delete a posting, select PATCH or DELETE and add the job posting ID to the endpoint (e.g., [Jobs API URL]/[Job ID]).

Example: https://www.kansasworks.com/api/jobs/10608445

Header

Headers provide meta information about the request. Add the following headers to your RESTful client:

Job API Headers
Header Name Header Value
Content-Type vnd.joblink.v2+json
Accept application/json; v2

Body

The request body contains the job posting data the client is sending to the AJL server.

Please note that if you were using Version 1 of the Jobs API, you can update the body text for additional fields.

Select the POST/PATCH Body link below to expand the Version 2 body.

{

"username": "string",
"api_token": "string",
"number_of_positions_available": 0,
"education_level_id": 0,
"license_type_id": 0,
"employment_type": "string",
"position_type": "string",
"alien_recruiting": "string",
"made_public_on": "string",
"absolute_expiration_on": "string",
"is_day_shift": true,
"is_evening_shift": true,
"is_night_shift": true,
"is_split_shift": true,
"is_no_preference_shift": true,
"is_rotating_shift": true,
"wage_upper_bound": 0,
"wage_lower_bound": 0,
"is_sent_to_jobcentral": true,
"is_staff_assistance_requested": true,
"applicant_reply_method": [
"string"
],
"application_description": "string",
"driving_required": true,
"is_wage_displayed": true,
"wage_type": "string",
"company_work_description": "string",
"title": "string",
"company_name": "string",
"city": "string",
"state": "string",
"zip": "string",
"address": "string",
"email": "string",
"phone": "string",
"fax": "string",
"url": "string",
"description": "string",
"average_hours": 0
}

{
"username": "string",
"api_token": "string"
}

About Jobs API Data

The following table (select link to expand) provides the keys and values accepted in the body of Jobs API requests. There are three types of data: string (group of characters and digits), integer (group of digits), and boolean (true or false). Accepted values are provided, as well as any constraints, such as character limits.

Jobs API Data
Key Data Type Value Constraints Required
username string Employer's AJL username 6-20 characters Yes
api_token string Employer's AJL Job API token 35 characters Yes
number_of_positions_available integer How many positions are available? 1-2 digits (a 422 error will occur if blank or if more than 2 digits) Yes
education_level_id integer What education level is required for this position?
  • 3 = Some high school or less
  • 4 = High school diploma or equivalent
  • 5 = Vocational certificate or credential
  • 6 = Some college
  • 7 = Associate's degree
  • 8 = Bachelor's degree
  • 9 = Masters degree
  • 10 = PhD
  • 11 = MD, OD or related
  • 12 = DDS, DMD or related
  • 13 = JD
  • 14 = Other Professional Degree
 1-2 digits (a 422 error will occur if the value is outside the defined range with the message "value is not a valid id") Yes
license_type_id integer If a driver's license is required, what class should it be:
  • 1 = Class A
  • 2 = Class B
  • 3 = Class C
  • 4 = Non-commercial driver's license
  • 5 = Class G
  • 6 = Class L
  • 7 = Class M
  • 8 = Class V
 1 digit (a 422 error will occur if the value is outside the defined range with the message "value is not a valid id") Yes
employment_type string Is this job full time, part time, or both?
  • F = full time
  • P = part time
  • N = full or part time
  • 3 = see job description
 1 character (if the value is outside of the defined range, the job will still be created and this key will be saved with a value of 3 by default) Yes
position_type string Is this job temporary, permanent, or both?
  • P = permanent
  • T = temporary
  • B = both
  • 3 = see job description
 1 character (if the value is outside of the defined range, the job will still be created and this key will be saved with a value of 3 by default) Yes
alien_recruiting string Is this job supporting an H-1B, H-2A, or H-2B recruitment activity?
  • 1 = H-1B
  • 2 = H-2A
  • 3 = H-2B
  • 0 = No
 1 character (a 422 error will occur if the value is outside the defined range with the message "value is not a valid recruitment_type") Yes
clearance_cds integer array Select the clearance level of this job posting:

  • 0 = Local

  • 1 = Intrastate

  • 2 = Interstate

 Must be an array containing 0, 1, and/or 2. Single and multiple values are accepted (a 422 error will occur if not in an array format or if the values are outside the defined range)

Example: [0, 1, 2]		 Yes, if "alien_recruiting" is set to 2 or 3
date_change_of_clearance_level string Date of clearance level change YYYY/MM/DD (a 422 error will occur if the format is incorrect) Yes, if "alien_recruiting" is set to 2 or 3
made_public_on string What date do you want this job made public? YYYY/MM/DD (an error will occur if the date is in the past) Yes
absolute_expiration_on string What is the expiration date of this job? YYYY/MM/DD (an error will occur if the date is in the past. This date must also be later than the start date in order for the job to be visible to the public) Yes
is_day_shift boolean Is this a day shift?

  • 0 = No

  • 1 = Yes

 1 character No
is_evening_shift boolean Is this an evening shift?

  • 0 = No

  • 1 = Yes

 1 character No
is_night_shift boolean Is this a night shift?

  • 0 = No

  • 1 = Yes

 1 character No
is_split_shift boolean Is this a split shift?

  • 0 = No

  • 1 = Yes

 1 character No
is_no_preference_shift boolean Is this an undefined shift?

  • 0 = No

  • 1 = Yes

 1 character No
is_rotating_shift boolean Is this a rotating shift?

  • 0 = No

  • 1 = Yes

 1 character No
wage_upper_bound integer What is the maximum starting wage or salary? Decimals and digits (e.g., 12.50 or 30000) Yes
wage_lower_bound integer What is the minimum starting wage or salary? Decimals and digits Yes
is_sent_to_jobcentral boolean Should this job be posted on US.jobs by Direct Employer?

  • 0 = No

  • 1 = Yes

 1 character No
is_staff_assistance_requested boolean Is staff assistance requested for managing this posting?

  • 0 = No

  • 1 = Yes

 1 character No
applicant_reply_method string array How should the applicant respond to this posting?
  • A = American Job Center
  • C = phone
  • E = email
  • F = fax
  • M = mail
  • P = in person
  • R = through recruiter
  • W = website

An error will occur if the value of this key is:

  • not a string array or a single character string

  • not a valid string

  • null or blank

 Yes
application_description string Describe any additional materials or information the applicant should provide. 16 characters No
driving_required boolean Is driving an essential function of this job?

  • 0 = No

  • 1 = Yes

 1 character Yes
is_wage_displayed boolean Should the wage be displayed for this position?

  • 0 = No

  • 1 = Yes

 1 character No
wage_type string How are wages paid for this position?
  • A = annual
  • H = hourly
  • O = other
 1 character Yes
company_work_description string What is the company description? 3000 characters No
title string What is the title of the position? 150 characters Yes
company_name string What is the name of the company? 150 characters (an error will occur if the value is over 150 characters) No
city string What city is the position located in? 25 characters Yes
state string What state is the position located in? 2 characters Yes
zip string What is the ZIP code of the position location? 9 characters Yes
address string What is the street address of the position location? 50 characters Yes
email string What is the company's email address? 100 characters (must have @ symbol, an error will occur if an invalid email address is used) No
phone string What is the company's phone number? 10 characters (an error will occur if the value is more than 10 digits, with or without dashes) No
fax string What is the company's fax number? 10 characters (an error will occur if the value is more than 10 digits, with our without dashes) No
url string What is the URL of the job posting, if available on an external website? 5000 characters (an error will occur if the value is not a valid URL) No
description string What is the job description? 4000 characters No
average_hours integer How many hours are in the average work week? (1-99) 2 characters Yes

Submitting a Successful API Request

Using your RESTful client, send a request to the Jobs API endpoint(s). All requests must include a valid employer username and API token; if this information is not valid, the request will not be successful. To be successful, POST requests must also include accepted values for all of the required fields in the AJL job posting builder as shown in the table above. The API processes successful requests immediately.

Once the job posting is created in AJL, both self-service employers and staff can view, edit, and delete the job posting like any other job. Job seekers can also search for and view the job posting like any other job, depending on the value submitted for “What date do you want this job made public?” and veterans’ preference settings in the state.

Status Codes

After submitting a request, a status code will display indicating the success of the request.

  • 200: The request has been fulfilled, resulting in the creation of a new resource.
  • 401: The request contained an unauthorized token, and access is denied.
  • 422: The request instance was invalid and validation messages are provided.
  • 500: An error indicating a general problem on our server during specific steps in processing.